home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2001 / MacHack 2001.toast / pc / The Hacks / pseudoDoc / gatherHeaderDoc.pl < prev    next >
Encoding:
Perl Script  |  2001-06-23  |  10.1 KB  |  276 lines
  1. #! /usr/bin/perl -w
  2. #
  3. # Script name: gatherHeaderDoc
  4. # Synopsis:     Finds all HeaderDoc generated docs in an input
  5. #        folder and creates a top-level HTML page to them
  6. #
  7. # Author: Matt Morse (matt@apple.com)
  8. # Last Updated: $Date: 2001/03/29 03:02:19 $
  9. # 
  10. # Copyright (c) 1999 Apple Computer, Inc.  All Rights Reserved.
  11. # The contents of this file constitute Original Code as defined in and are
  12. # subject to the Apple Public Source License Version 1.1 (the "License").
  13. # You may not use this file except in compliance with the License.  Please
  14. # obtain a copy of the License at http://www.apple.com/publicsource and
  15. # read it before using this file.
  16. #
  17. # This Original Code and all software distributed under the License are
  18. # distributed on an TAS ISU basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  19. # EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  20. # INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS
  21. # FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the License for
  22. # the specific language governing rights and limitations under the
  23. # License.
  24. #
  25. # $Revision: 1.3 $
  26. ######################################################################
  27. use Cwd;
  28. use File::Find;
  29. use File::Copy;
  30.  
  31. my $pathSeparator;
  32. my $isMacOS;
  33. my $scriptDir;
  34. my $framesetFileName;
  35. my $masterTOCFileName;
  36. BEGIN {
  37.     if ($^O =~ /MacOS/i) {
  38.             $pathSeparator = ":";
  39.             $isMacOS = 1;
  40.     } else {
  41.             $pathSeparator = "/";
  42.             $isMacOS = 0;
  43.     }
  44. }
  45.  
  46. use strict;
  47. use FindBin qw ($Bin);
  48. use lib "$Bin"."$pathSeparator"."Modules";
  49.  
  50. # Modules specific to gatherHeaderDoc
  51. use HeaderDoc::DocReference;
  52. use HeaderDoc::Utilities qw(findRelativePath safeName getAPINameAndDisc printArray printHash updateHashFromConfigFiles getHashFromConfigFile);
  53.  
  54. my $debugging = 1;
  55. ######################################## Design Overview ###################################
  56. # - We scan input directory for frameset files (index.html, by default).
  57. # - For each frameset file, we look for a special HTML comment (left by HeaderDoc)
  58. #   that tell us the name of the header/class and the type (header or cppclass). 
  59. # - We create a DocReference object to store this info, and also the path to the
  60. #   frameset file.
  61. # - We run through array of DocRef objs and create a master TOC based on the info
  62. # - Finally, we visit each TOC file in each frameset and add a "[Top]" link
  63. #   back to the master TOC.  [This is fragile in the current implementation, since
  64. #   we find TOCs based on searching for a file called "toc.html" in the frameset dir.
  65. # 
  66. ########################## Setup from Configuration File #######################
  67. my $localConfigFileName = "headerDoc2HTML.config";
  68. my $preferencesConfigFileName = "com.apple.headerDoc2HTML.config";
  69. my $homeDir = (getpwuid($<))[7];
  70. my $usersPreferencesPath = $homeDir.$pathSeparator."Library".$pathSeparator."Preferences";
  71. my @configFiles = ($Bin.$pathSeparator.$localConfigFileName, $usersPreferencesPath.$pathSeparator.$preferencesConfigFileName);
  72.  
  73. # default configuration, which will be modified by assignments found in config files.
  74. # The default values listed in this hash must be the same as those in the identical 
  75. # hash in headerDoc2HTML--so that links between the frameset and the masterTOC work.
  76. my %config = (
  77.     defaultFrameName => "index.html", 
  78.     masterTOCName => "MasterTOC.html"
  79. );
  80.  
  81. %config = &updateHashFromConfigFiles(\%config,\@configFiles);
  82.  
  83. if (defined $config{"defaultFrameName"}) {
  84.     $framesetFileName = $config{"defaultFrameName"};
  85. } 
  86. if (defined $config{"masterTOCName"}) {
  87.     $masterTOCFileName = $config{"masterTOCName"};
  88. } 
  89.  
  90. ########################## Input Folder and Files #######################
  91. my @inputFiles;
  92. my $inputDir;
  93.  
  94. if (($#ARGV == 0) && (-d $ARGV[0])) {
  95.     $inputDir = $ARGV[0];
  96.     $inputDir =~ s|(.*)/$|$1|; # get rid of trailing slash, if any
  97.     if ($inputDir !~ /^\//) { # not absolute path -- !!! should check for ~
  98.         my $cwd = cwd();
  99.         $inputDir = $cwd.$pathSeparator.$inputDir;
  100.     }
  101.     &find({wanted => \&getFiles, follow => 1}, $inputDir);
  102. } else {
  103.     die "You must specify a single input directory for processing.\n";
  104. }
  105. unless (@inputFiles) { print "No valid input files specified. \n\n";};
  106.  
  107. sub getFiles {
  108.     my $filePath = $File::Find::name;
  109.     my $fileName = $_;
  110.     
  111.     if ($fileName =~ /$framesetFileName/) {
  112.         push(@inputFiles, $filePath);
  113.     }
  114. }
  115. ########################## Find HeaderDoc Comments #######################
  116. my @headerFramesetRefs;
  117. my @classFramesetRefs;
  118.  
  119. my $oldRecSep = $/;
  120. undef $/; # read in files as strings
  121.  
  122. foreach my $file (@inputFiles) {
  123.     open (INFILE, "<$file") || die "Can't open $file: $!\n";
  124.     my $fileString = <INFILE>;
  125.     close INFILE;
  126.     if ($fileString =~ /<--\s+(headerDoc\s*=.*?)-->/) {
  127.         my $fullComment = $1;
  128.         my @pairs = split(/;/, $fullComment);
  129.         my $docRef = HeaderDoc::DocReference->new;
  130.         $docRef->path($file);
  131.         foreach my $pair (@pairs) {
  132.             my ($key, $value) = split(/=/, $pair);
  133.             $key =~ s/^\s+|\s+$//;
  134.             $value =~ s/^\s+|\s+$//;
  135.             SWITCH: {
  136.                 ($key =~ /headerDoc/) && 
  137.                     do {
  138.                         $docRef->type($value);
  139.                         last SWITCH;
  140.                     };
  141.                 ($key =~ /name/) && 
  142.                     do {
  143.                         $docRef->name($value);
  144.                         last SWITCH;
  145.                     };
  146.             }
  147.         }
  148.         my $tmpType = $docRef->type();
  149.         if ($tmpType eq "Header") {
  150.             push (@headerFramesetRefs, $docRef);
  151.         } elsif ($tmpType eq "CPPClass") {
  152.             push (@classFramesetRefs, $docRef);
  153.         } else {
  154.             my $tmpName = $docRef->name();
  155.             my $tmpPath = $docRef->path();
  156.             print "Unknown type '$tmpType' for document with name '$tmpName' and path '$tmpPath'\n";
  157.         }
  158.     }
  159. }
  160. $/ = $oldRecSep;
  161.  
  162. # create master TOC if we have any framesets
  163. if (scalar(@headerFramesetRefs) + scalar(@classFramesetRefs)) {
  164.     &printMasterTOC();
  165.     &addTopLinkToFramesetTOCs();
  166. } else {
  167.     print "gatherHeaderDoc.pl: No HeaderDoc framesets found--returning\n" if ($debugging); 
  168.     return;
  169. }
  170. exit 0;
  171.  
  172. ################### Print Navigation Page #######################
  173. sub printMasterTOC {
  174.     my $outputDir = $inputDir;
  175.     my $masterTOC = $outputDir.$pathSeparator. $masterTOCFileName;
  176.     my $headersLinkString= '';
  177.     my $classesLinkString = '';
  178.     my $fileString;
  179.     my $localDebug = 0;
  180.     
  181.     # get the HTML links to each header 
  182.     foreach my $ref (sort objName @headerFramesetRefs) {
  183.         my $name = $ref->name();
  184.         my $path = $ref->path();        
  185.         my $tmpString = &getLinkToFramesetFrom($masterTOC, $path, $name);
  186.         $headersLinkString .= $tmpString;
  187.     }
  188.     print "\$headersLinkString is '$headersLinkString'\n" if ($localDebug);
  189.     
  190.     # get the HTML links to each class 
  191.     foreach my $ref (sort objName @classFramesetRefs) {
  192.         my $name = $ref->name();
  193.         my $path = $ref->path();        
  194.         my $tmpString = &getLinkToFramesetFrom($masterTOC, $path, $name);
  195.         $classesLinkString .= $tmpString;
  196.     }
  197.     if (($localDebug) && length($classesLinkString)) {print "\$classesLinkString is '$classesLinkString'\n";};
  198.     
  199.     # put together header/footer with linkString--could use template
  200.     my $htmlHeader = "<html><head><title>Header Documentation</title></head><body bgcolor=\"#cccccc\"><h1>Header Documentation</h1><hr><br>\n";
  201.     my $headerSection = "<h2>Headers</h2>\n<blockquote>\n".$headersLinkString."\n</blockquote>\n";
  202.     my $classesSection = '';
  203.     if (length($classesLinkString)) {
  204.         $classesSection = "<h2>Classes</h2>\n<blockquote>\n".$classesLinkString."\n</blockquote>\n";
  205.     }
  206.     my $htmlFooter = "</body>\n</html>\n";
  207.     $fileString = $htmlHeader.$headerSection.$classesSection.$htmlFooter;
  208.     
  209.     # write out page
  210.     print "gatherHeaderDoc.pl: writing master TOC to $masterTOC\n" if ($localDebug);
  211.     open(OUTFILE, ">$masterTOC") || die "Can't write $masterTOC.\n";
  212.     print OUTFILE $fileString;
  213.     close OUTFILE;
  214. }
  215.  
  216. sub addTopLinkToFramesetTOCs {
  217.     my $masterTOC = $inputDir.$pathSeparator. $masterTOCFileName;
  218.     my $tocFileName = "toc.html";
  219.     my @allDocRefs;
  220.     push(@allDocRefs, @headerFramesetRefs);
  221.     push(@allDocRefs, @classFramesetRefs);
  222.     my $localDebug = 0;
  223.     
  224.     foreach my $ref (@allDocRefs) {
  225.         my $name = $ref->name();
  226.         my $type = $ref->type();
  227.         my $path = $ref->path();
  228.         my $tocFile = $path;                   # path to index.html
  229.         my $fsName = quotemeta($framesetFileName);
  230.         $tocFile =~ s/$fsName$/toc.html/;         # path to toc.html
  231.         
  232.         if (-e "$tocFile" ) {
  233.             my $oldRecSep = $/;
  234.             undef $/; # read in file as string
  235.             open(INFILE, "<$tocFile") || die "Can't read file $tocFile.\n";
  236.             my $fileString = <INFILE>;
  237.             close INFILE;
  238.             $/ = $oldRecSep;
  239.             
  240.             my $uniqueMarker = "headerDoc=\"topLink\"";
  241.             if ($fileString !~ /$uniqueMarker/) { # we haven't been here before
  242.                 my $relPathToMasterTOC = &findRelativePath($tocFile, $masterTOC);
  243.                 my $topLink = "\n<font size=\"-2\"><a href=\"$relPathToMasterTOC\" target=\"_top\" $uniqueMarker>[Top]</a></font><br>\n";
  244.                 
  245.                 $fileString =~ s/(<body[^>]*>)/$1$topLink/i;
  246.             
  247.                 open (OUTFILE, ">$tocFile") || die "Can't write file $tocFile.\n";
  248.                 print OUTFILE $fileString;
  249.                 close (OUTFILE);
  250.             }
  251.         } elsif ($debugging) {
  252.             print "--> '$tocFile' doesn't exist!\n";
  253.             print "Cannot add [top] link for frameset doc reference:\n";
  254.             print "   name: $name\n";
  255.             print "   type: $type\n";
  256.             print "   path: $path\n";
  257.         }
  258.     }
  259. }
  260.  
  261. sub getLinkToFramesetFrom {
  262.     my $masterTOCFile = shift;
  263.     my $dest = shift;    
  264.     my $name = shift;    
  265.     my $linkString;
  266.     
  267.     my $relPath = &findRelativePath($masterTOCFile, $dest);
  268.     $linkString = "<a href=\"$relPath\" target =\"_top\">$name</a><br>\n"; 
  269.     return $linkString;
  270. }
  271.  
  272.  
  273. sub objName { # for sorting objects by their names
  274.     uc($a->name()) cmp uc($b->name());
  275. }
  276.